Add docs for foreman_ansible_director plugin by maximiliankolb · Pull Request #4730 · theforeman/foreman-documentation

maximiliankolb · 2026-03-23T13:19:15Z

What changes are you introducing?

This patch adds a guide to provide documentation for the Ansible Director plugin.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.18/Katello 4.20 (Satellite 6.19)
Foreman 3.17/Katello 4.19
Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6 and 7.7)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
We do not accept PRs for Foreman older than 3.12.

github-actions · 2026-03-23T13:23:26Z

The PR preview for c7b3dcf is available at theforeman-foreman-documentation-preview-pr-4730.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

This patch adds a guide to provide documentation for the Ansible Director plugin. Refs https://community.theforeman.org/t/how-to-refer-to-kebab-menus/45994/4?u=maximilian Refs https://github.com/ATIX-AG/foreman_ansible_director/ Refs https://github.com/ATIX-AG/smart_proxy_ansible_director/

All entities created by users are scoped by orgs.

aneta-petrova · 2026-04-02T14:37:50Z

guides/common/modules/con_set-up-ansible-integration-with-project.adoc

+By default, {Team} supports Ansible that is packaged for the platform your {ProjectServer} or {SmartProxyServer} runs on.
+If you want to configure different client platforms that rely on different Ansible or Python versions, you can use the Ansible Director plugin.
+The Ansible Director plugin allows you to manage Ansible content, Ansible Execution Environments, and Ansible environments independent of your {Project} platform.
+
+// TODO: Reword to better explain that you can technically use them in parallel but it's most likely not necessary.
+You can use the Ansible plugin and Ansible Director plugin simultaneously on {Project} but they are unrelated.


Could this be split out into a separate overview-like chapter?

aneta-petrova · 2026-04-02T14:40:20Z

guides/common/assembly_import-and-manage-ansible-content.adoc

@@ -0,0 +1,33 @@
+:_mod-docs-content-type: ASSEMBLY


There are a lot of sections here (15). So that made me think: How to reduce the number of modules?

The idea I had was to reconsider what the user story is. Rather than "I want to import..."/"I want to delete...", should the main focus in fact be "I want to manage and be in control of my Ansible content"? That's a tiny shift in mindset but could help redesign the procedures into something like:

In the web UI, go to XYZ to view your current Ansible content.

Want to add something? Go to Import Ansible content.

Want to remove something? Go to Delete Ansible content.

View the list of content again to check it's all to your liking now.

It could be a way to reduce the number of procedures because you'd effectively combine them into a smaller list of more wholesome procedures that cover more, but in context of what the user's actual goal is.

This applies to some of the other assemblies as well so I'd suggest to look at options for reimagining the underlying user stories there as well.

aneta-petrova · 2026-04-02T14:42:52Z

guides/common/modules/proc_import-ansible-content-from-ansible-galaxy-by-using-web-ui.adoc

+.Prerequisites
+* Your {Project} account has a role that grants the `create_ansible_content`, `view_ansible_content`, and `view_organizations` permissions.
+
+.Procedure


This is a very long procedure (like many of the other web UI procedures here). Downstream, we now have a (soft) limit on max 10 steps per procedure. This one is already at 10 steps. Is there a way to document fewer steps and rely on the instructions in the web UI more? In other words: what can the user figure out on their own from the interface, so that we don't have to document it explicitly? The workflow itself doesn't look too complex (it's just about filling a form...) but the procedure makes it look complex, just due to the sheer number of the steps involved.

maximiliankolb · 2026-04-08T07:10:06Z

TODO

Mention two roles provided by the plugin:

AnsibleDirector Manager: This role contains every permission defined by the plugin and can be used to limit a users scope to only this plugin.
AnsibleDirector Viewer: This role contains every read-only (i.e. begins with view_) permission defined by the plugin. A user with this role can only see/query data relating to the plugin.

nadjaheitmann

Thanks @maximiliankolb ! Huge PR!

nadjaheitmann · 2026-04-10T12:51:16Z

guides/common/modules/proc_import-ansible-content-based-on-a-yml-file-by-using-web-ui.adoc

+
+.Verification
+. In the {ProjectWebUI}, navigate to *Ansible* > *Content*.
+. For your imported Ansible content, click the *arrow* symbol to view the list of imported version.


Suggested change

. For your imported Ansible content, click the *arrow* symbol to view the list of imported version.

. For your imported Ansible content, click the *arrow* symbol to view the list of imported versions.

nadjaheitmann · 2026-04-10T12:52:02Z

guides/common/modules/proc_import-ansible-content-from-a-git-repository-by-using-web-ui.adoc

+
+.Verification
+. In the {ProjectWebUI}, navigate to *Ansible* > *Content*.
+. For your imported Ansible content, click the *arrow* symbol to view the list of imported version.


Suggested change

. For your imported Ansible content, click the *arrow* symbol to view the list of imported version.

. For your imported Ansible content, click the *arrow* symbol to view the list of imported versions.

nadjaheitmann · 2026-04-10T12:52:32Z

guides/common/modules/proc_import-ansible-content-from-ansible-galaxy-by-using-web-ui.adoc

+
+.Verification
+. In the {ProjectWebUI}, navigate to *Ansible* > *Content*.
+. For your imported Ansible content, click the *arrow* symbol to view the list of imported version.


Suggested change

. For your imported Ansible content, click the *arrow* symbol to view the list of imported version.

. For your imported Ansible content, click the *arrow* symbol to view the list of imported versions.

nadjaheitmann · 2026-04-10T12:52:58Z

guides/common/modules/proc_import-ansible-content-based-on-a-yml-file-by-using-api.adoc

+= Import Ansible content based on a YML file by using {Project} API
+
+[role="_abstract"]
+You can import Ansible content based on a YML file into {Project} by using {ProjectWebUI}.


That should be API not web ui

nadjaheitmann · 2026-04-10T12:53:16Z

guides/common/modules/proc_customize-default-values-of-ansible-variables-by-using-api.adoc

+--user "_My_User_Name_:__My_Password__" \
+https://{foreman-example-com}/api/v2/ansible_director/ansible_content/_My_Ansible_Content_ID_/ \
+| jq ".roles [] .name"
+----


Why not note down the ID of the Ansible content?

nadjaheitmann · 2026-04-10T13:05:18Z

...gn-an-ansible-execution-environment-to-an-ansible-lifecycle-environment-by-using-web-ui.adoc

+
+.Verification
+. In the {ProjectWebUI}, navigate to *Ansible* > *Environments*.
+. Verify that {Project} shows your newly assign Ansible Execution Environment for your selected Ansible lifecycle environment.


. Verify that {Project} shows your newly assigned Ansible Execution Environment for your selected Ansible lifecycle environment.

nadjaheitmann · 2026-04-10T13:05:49Z

guides/common/modules/proc_unassign-ansible-roles-from-a-host-by-using-api.adoc

+--request PUT \
+--user "_My_User_Name_:__My_Password__" \
+https://{foreman-example-com}/api/v2/ansible_director/lifecycle_environments/_My_Ansible_Lifecycle_Environment_ID_/ \
+| jq


It looks exactly the same as assigning roles. Is that correct?

nadjaheitmann · 2026-04-10T13:06:48Z

guides/common/modules/proc_run-an-ansible-playbook-on-a-host-by-using-web-ui.adoc

+. Click *Run Job*.
+. From the *Job category* menu, select `Ansible Playbook`.
+// TODO: Yes, really!?!
+. From the *Job template* menu, select `Apply cool playbook`.


nadjaheitmann · 2026-04-10T13:07:01Z

guides/common/modules/proc_run-an-ansible-playbook-on-a-host-by-using-web-ui.adoc

+.Verification
+. In the {ProjectWebUI}, navigate to *Monitor* > *Jobs*.
+// TODO: Yes, really!?!
+. In the search bar, enter `Run cool playbook`.


nadjaheitmann · 2026-04-10T13:07:38Z

guides/common/modules/ref_ansible-director-settings.adoc

+= Ansible Director settings
+
+[role="_abstract"]
+The Ansible Director settings define the {Project}-wide settings of the Ansible Director plugin.


Suggested change

The Ansible Director settings define the {Project}-wide settings of the Ansible Director plugin.

The Ansible Director settings define the {Project}-wide settings of this plugin.

IMHO, it is clear that the settings are for the Ansible Director plugin, so no need to write it twice. But it might be worth noting that there is a separate tab for the Ansible Director settings which is called 'Ansible Director' (there are also tabs called 'Ansible' and 'Config Management').

pr-processor bot added the Not yet reviewed label Mar 23, 2026

github-actions bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Mar 23, 2026

maximiliankolb force-pushed the foreman_ansible_director branch 5 times, most recently from 98e10f6 to c2fbee3 Compare April 1, 2026 13:43

maximiliankolb force-pushed the foreman_ansible_director branch from c2fbee3 to d279598 Compare April 2, 2026 10:08

maximiliankolb added 4 commits April 2, 2026 13:32

FIXIP Fix API to delete AC

9a4ac08

FIXUP Explain that AC, ALE, and AEE belong to orgs

2b1cd66

All entities created by users are scoped by orgs.

FIXUP Add supported Python versions

9e56306

FIXUP: Add option to run foreman_ansible and foreman_ansible_director

faa6f4c

aneta-petrova reviewed Apr 2, 2026

View reviewed changes

pr-processor bot removed the Not yet reviewed label Apr 2, 2026

FIXUP Fix typo

c7b3dcf

nadjaheitmann reviewed Apr 10, 2026

View reviewed changes

	. For your imported Ansible content, click the arrow symbol to view the list of imported version.
	. For your imported Ansible content, click the arrow symbol to view the list of imported versions.

	The Ansible Director settings define the {Project}-wide settings of the Ansible Director plugin.
	The Ansible Director settings define the {Project}-wide settings of this plugin.

Conversation

maximiliankolb commented Mar 23, 2026

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Uh oh!

github-actions bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maximiliankolb commented Apr 8, 2026

TODO

Uh oh!

nadjaheitmann left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Mar 23, 2026 •

edited

Loading